Skip to content

Scaling E2: one CDN cache rule for soul.game that the release's own check accepts (#2514) - #2574

Merged
genekogan merged 4 commits into
mainfrom
agent/2514-cdn-cache-rules
Nov 16, 2026
Merged

genekogan merged 4 commits into
mainfrom
agent/2514-cdn-cache-rules

Conversation

@genekogan

Copy link
Copy Markdown
Member

Problem

Every release runs cdn-walk, which fails any hashed or release-stable origin response whose cache status is DYNAMIC or BYPASS (tools/cdn/origin-cache.mjs). A CDN caches by extension by default and never JSON or extension-less paths, so the day soul.game is proxied, parts, profile photos and the snapshot would read DYNAMIC and fail every release. The zone's rules were not in the repository. Closes #2514.

Base: E1's branch agent/2513-cdn-front until it lands, then main.

Acceptance

  • A1 tools/cdn/origin-cache.test.* (or a new test) shows every hashed and stable class accepted with a cache status of hit or miss and refused with dynamic or bypass, matching the documented rule. — evidence: node --test tools/cdn/origin-cache.test.mjs -> test "E2 A1" passes: one sample per hashed and stable class (bundle, stored object at root and per world, part, art, profile photo, /modular, /mars-assets, /world-assets, a font) is eligible under cdnCacheEligible, gives no problem with HIT, MISS, EXPIRED or REVALIDATED and a Cloudflare DYNAMIC/BYPASS problem otherwise; the page, /v1/config, the world list, /__sim/*, edge and god routes are not eligible. Test "E2 A3" checks cdn.md carries cdnRuleExpression() verbatim.
  • A2 The check script's cache section passes against a local caching proxy configured from the documented rule. — evidence: node --test tools/cdn/origin-cache.test.mjs -> "E2 A2" passes, output:
    cache: bundle /assets/index-AbCd1234.js: 200 MISS, then 200 HIT
    cache: part /w/eden/v1/world/part/abababababababababababababababab: 200 MISS, then 200 HIT
    cache: stable /mars-assets/draco/draco_decoder.wasm: 200 MISS, then 200 HIT
    cache: snapshot /w/eden/v1/world/snapshot?defs=ref&cols=1&v=41.2.7: 200 MISS, then 200 HIT
    cache: stale snapshot key: 200 BYPASS no-store
    PASS
    
    The same check fails for part and snapshot behind a stand-in with the CDN's by-extension default, and fails when the origin lets a stale key be cached.
  • A3 The documented rule set and the two runbook lines are in docs/operations/cdn.md. — evidence: docs/operations/cdn.md "The cache rule" (expression, four settings, why it is safe); purge lines for a moderation veto and after a restore in docs/operations/runbook.md (in Touches), linked from the rule.

Proof

Tier: T1 (node tools/proof/tier.mjs --files <the five files> -> T1, from check-soul-game.mjs)

  • proof.json: not required at T1
  • clips: not required at T1
  • images: none

Self-audit

  • Checks run: node --test tools/cdn/origin-cache.test.mjs tools/world-launcher/check-soul-game.test.mjs -> 13 pass, 0 fail, 0 skipped (the E1 Caddy tests ran with the local caddy). No typecheck: only .mjs tools and docs changed. node .github/scripts/guards.mjs scrub --base origin/agent/2513-cdn-front -> 0 problems.
  • Failed attempts: none.
  • Long tail / externalities: none at runtime: nothing in the server or client changes. checkSoulGame's default points stay the six of E1 (its tests unchanged); the CLI runs all seven, so before the record is proxied it fails address and cache (documented).
  • Known limits: the stand-in CDN emulates the rule's eligibility and "respect origin" TTLs, not Cloudflare itself; the hands-on check after the switch is the real proof. Edge caches are per site, so the check's hit says nothing about other locations (said in the doc). The rule uses strict wildcard, which every plan has; purging by prefix needs a plan that has it, else purge everything (runbook).
  • Docs: docs/operations/cdn.md (rule, check's new point, hands-on step 5 now links the rule), docs/operations/runbook.md (purges).

Deviations from the design

  • The rule is written as path patterns in origin-cache.mjs (CDN_CACHE_RULE) that produce both the predicate the tests use and the expression the doc carries, so the doc cannot drift from the classes. It uses soul.game's root-launcher paths (no /worlds prefix).
  • The A2 test lives in tools/cdn/origin-cache.test.mjs (in Touches) rather than check-soul-game.test.mjs (outside Touches). The cache point is not in checkSoulGame's default list for the same reason: E1's tests run the default list against a stand-in without a world page.
  • The listed alternative (tolerating DYNAMIC) was not needed: every class can be made eligible.

Outside Touches

None.

Time

Started 07:40 UTC, PR ready at about 07:55 UTC: about 15 minutes against a 2 h ceiling.

Changelog

no-changelog: tools and operations docs only; nothing a visitor or agent sees changes until the hands-on switch.

Risk

None at runtime. The rule takes effect only when the operator applies it with the switch (hands-on step 5). If a path it makes eligible ever answered per user with a public cache header, the edge would share it; the rule excludes /v1/ and /__sim/ from static patterns and lists only three public API reads for that reason. Rollback is deleting the rule in the zone.

🤖 Generated with Claude Code

genekogan and others added 3 commits November 16, 2026 02:36
…s own address (#2513)

A site file (soul-game.caddy) replaces X-Forwarded-For with exactly {client_ip}; a trust snippet imported in the
Caddyfile's global options trusts CF-Connecting-IP only from the CDN's published ranges. GET /__sim/whoami answers the
address the launcher keyed a request on, and deploy/caddy/check-soul-game.mjs checks six points from outside.
docs/operations/cdn.md carries the ordered hands-on steps and the rollback.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…eck accepts, with a check that proves the hit (#2514)

The rule's paths are derived from origin-cache.mjs's hashed and stable classes plus the keyed snapshot;
cdn.md carries the expression verbatim (tested), check-soul-game.mjs gains a cache point (each class twice,
the second a hit; a stale snapshot key no-store), and the runbook says when to purge.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@genekogan
genekogan marked this pull request as ready for review November 16, 2026 07:50
@genekogan genekogan added ci:run Open the CI window: run this ready PR's heavy CI jobs (docs/testing.md#ci-window) no-changelog Nothing user-facing; no changes/ fragment needed labels Nov 16, 2026
@github-actions

github-actions Bot commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

Proof check: proof-ok passes

Tier T1 from tools/world-launcher/deploy/caddy/check-soul-game.mjs (node tools/proof/tier.mjs).
Required at T1 (docs/process/PROOF-POLICY.yml): focused node --test of touched files; typecheck of touched packages.

Check Status Detail
problem statement ok present
linked issue ok #2514
acceptance ok 3/3 met
carried from the issue ok all 3 issue criteria present
self-audit ok checks, failed attempts, long tail and limits filled
Acceptance criteria
Criterion Status Evidence
[x] A1 tools/cdn/origin-cache.test.* (or a new test) shows every hashed and met node --test tools/cdn/origin-cache.test.mjs -> test "E2 A1" passes: one sample per hashed and stable class (bundle, st
[x] A2 The check script's cache section passes against a local caching proxy met node --test tools/cdn/origin-cache.test.mjs -> "E2 A2" passes, output:
[x] A3 The documented rule set and the two runbook lines are in `docs/operati met docs/operations/cdn.md "The cache rule" (expression, four settings, why it is safe); purge lines for a moderation veto

Proof links: 0 video, 0 image, no proof.json.

Updated on every edit, push, label and review. How to fill it: .claude/skills/journal/SKILL.md. T3-T4 also need the maintainer's sign-off (tools/proof/gate.mjs). A maintainer can waive with the proof:waived label.

@genekogan genekogan added merge:ready Hand the PR to the merge train (.github/workflows/merge-train.yml) ci:run Open the CI window: run this ready PR's heavy CI jobs (docs/testing.md#ci-window) and removed ci:run Open the CI window: run this ready PR's heavy CI jobs (docs/testing.md#ci-window) labels Nov 16, 2026
Base automatically changed from agent/2513-cdn-front to main November 16, 2026 11:46
3-way merge against the fork point from the old base (3b984bb), by .github/scripts/restack.mjs.
@genekogan

Copy link
Copy Markdown
Member Author

Restack: #2567 squash-merged into main.

main was merged forward with a 3-way merge against this branch's fork point from the old base (3b984bb), so files this PR does not change take the squashed content and the diff is this PR's own changes again.

Head e29b008 → 6690f07 (fast-forward push, no force).

@genekogan genekogan added ci:run Open the CI window: run this ready PR's heavy CI jobs (docs/testing.md#ci-window) and removed ci:run Open the CI window: run this ready PR's heavy CI jobs (docs/testing.md#ci-window) labels Nov 16, 2026
@genekogan
genekogan enabled auto-merge November 16, 2026 11:58
@genekogan
genekogan added this pull request to the merge queue Nov 16, 2026
@genekogan genekogan added ci:run Open the CI window: run this ready PR's heavy CI jobs (docs/testing.md#ci-window) and removed ci:run Open the CI window: run this ready PR's heavy CI jobs (docs/testing.md#ci-window) labels Nov 16, 2026
Merged via the queue into main with commit 8ccb753 Nov 16, 2026
49 of 53 checks passed
@genekogan
genekogan deleted the agent/2514-cdn-cache-rules branch November 16, 2026 12:41
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

ci:run Open the CI window: run this ready PR's heavy CI jobs (docs/testing.md#ci-window) merge:ready Hand the PR to the merge train (.github/workflows/merge-train.yml) no-changelog Nothing user-facing; no changes/ fragment needed

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Scaling E2 · Cache rules that the release's own CDN check accepts, written down and verified

1 participant